cggm2 Plugin Reference

A jquery ui plugin to aide in building google maps within CMSMS.

Introduction
Features
License
Support
Dependencies
Usage
Methods
Options
Events
The MarkerOptions Object
The Icon Object
The KML Object
The Near Future
Examples
Credits

Introduction:

This plugin is included with the CGGoogleMaps2 module for CMS Made Simple. It is a plugin written using the jquery ui widget factory to aide in building and interacting with google maps.

This plugin in conjunction with the dynamic nature of CMS Made Simple, Smarty templates, and the flexible way in which markers can be extracted from CMSMS Modules allows building flexible and dynamic maps.

This document describes the cggm2 jquery plugin and how to interact with it in pure html/javascript. It does not really touch on the behavior of the CGGoogleMaps2 module that wraps this plugin.

Features:

Multiple independent maps on one page
Dynamic Markers
Automatic Centering (optional)
Streetview controls
Tooltips that can be styled and contain HTML
Flexible InfoWindow that can be styled and contain HTML
Create markers from HTML
geolocation (sensor) support
Flexible Icon mechanism
KML Overlays
Pan to Marker via javascript
Dynamically open info-windows
Dynamic Directions

License:

Support:

Dependencies:

Jquery
The google maps API with the geometry library, and sensor support.
jquery-ui (widget factory)
map_tooltip.js (this provides the extended tooltip functionality for hovering over markers)
infobox plugin (provides a stylable infowindow)

Usage:

Usage of this plugin is simple and straight forward. There are only 3 basic steps:

Include the required javascript libraries
The libraries can be included from a CDN, or downloaded locally and stored on your server. The required libraries are:
1. jquery 1.10+
2. jquery-ui 1.11+
3. jquery.cggm_map.js (this is shipped with the CGGoogleMaps2 module and is located in the module's lib/js directory)
4. infobox.packed.js (this is also distributed with the CGGoogleMaps2 module and is located in the module's lib/js directory)
5. map_tooltip.js (also distributed with CGGoogleMaps2).
Create a div of the appropriate size to hold your map.
Initialize the cggm2 plugin, creating at least one marker, or a center coordinate.

Initializing the plugin is done via the standard jquery mechanism. i.e: $('selector').cggm2(options);

Note: Though it is possible to initialize the map with no markers or center coordinate, the map may be centered around latitude and longitude 0.

Test1 illustrates creating a simple map with a single point. To see how this is done, you can view the page's source code.

Calling plugin methods:

The cggm2 plugin has numerous methods to interact with the map. To call a method in the plugin you use this syntax: $('selector').cggm2('method'[,argument1[,argument2]]);

Retrieving plugin options:

Retrieving the value of an option after construction can be achieved by calling the 'option' method, with a syntax such as:

$('selector').cggm2('option','name');

The type of the return value depends on the name of the option you are retrieving.

Changing plugin options:

Adjusting an option in the plugin after construction can be done by calling the 'option' method, with a syntax such as:

$('selector').cggm2('option','name',value);

The type of the value depends upon the option you are setting. See the documentation below for the specific options. It is possible for the map to break or misbehave if invalid data is specified in an option. The map may update to represent the changed option.

Adding Static Markers:

The cggm2 jquery plugin allows creating map markers from statically coded HTML. This allows creating markers in a variety of ways (i.e: dynamically extracting data from the database, outputting relevant data to HTML to be displayed on a map. It is very straight forward to do.

Create a div with the class cggm2_markers directly after your map div.
For each static marker that you would like to create create a new div with the class cggm2_marker within the div created above.
create a series of hidden input elements with the classes cggm2_marker_name, cggm2_marker_title, cggm2_marker_description, cggm2_marker_latitude, cggm2_marker_longitude, and cggm2_marker_icon to hold the respective data.

You should see something like this:

<div id="map"></div>
   <div class="cggm2_markers" style="display: none;">
  <div class="cggm2_marker">
    <input type="hidden" class="cggm2_marker_name" value="marker_1"/>
    <input type="hidden" class="cggm2_marker_title" value="Calgary"/>
    <input type="hidden" class="cggm2_marker_description" value="The Oil and Gas capitol of Canada"/>
    <input type="hidden" class="cggm2_marker_latitude" value="51.0500"/>
    <input type="hidden" class="cggm2_marker_longitude" value="-114.0667"/>
  </div>
  <div class="cggm2_marker">
    <input type="hidden" class="cggm2_marker_name" value="marker_2"/>
    <input type="hidden" class="cggm2_marker_title" value="Edmonton"/>
    <input type="hidden" class="cggm2_marker_description" value="The capitol of the province of Alberta"/>
    <input type="hidden" class="cggm2_marker_latitude" value="53.5333"/>
    <input type="hidden" class="cggm2_marker_longitude" value="-113.5000">
  </div>
</div>

You can see a working example of building a map from static HTML in Test4.

Methods:

getMap:

This method returns the google Map object used internally by the cggm2 plugin.

usage:

var map = $('#map').cggm2('getMap');

addMarker:

This method accepts a markerOptions object and will dynamically add a new marker to the map. Test3 illustrates example usage of this method. View the page source to see how it is used.

usage:

var marker_opts = {
    name: 'test',
    position:  [ '-41.21212', '-112.12345' ],
    title: 'Sample Marker',
    description:  'This is a sample marker, with a larger description',
};
$('#map').cggm2('addMarker',marker_opts);

getMarker:

This method returns the google maps Marker object for the requested marker If the named marker cannot be found, false is returned. Test3 illustrates example usage of this method. View the page source to see how it is used.

usage:

var marker = $('#map').cggm2('getMarker','test');

getMarkerList:

This method returns an array of known marker names.

usage:

var marker_names = $('#map').cggm2('getMarkerList');

removeMarker:

This method will remove the named marker from the map. Test3 illustrates example usage of this method. View the page source to see how it is used.

usage:

$('#map').cggm2('removeMarker','test');

removeAllMarkers:

This method will remove all markers from the map. Markers will then need to be added back with the addMarker method. Test3 illustrates example usage of this method. View the page source to see how it is used.

usage:

$('#map').cggm2('removeAllMarkers');

getDirections:

This method is used to retrieve and display route information (directions) between two markers (by name). In order to use this functionality, the directions option must be enabled. Then, depending upon other settings, and parameters passed in this method will perform differently:

If directions_draw is enabled, and the directions service can successfully calculate a route, then the route will be displayed on the map.
if a proper value for directions_panel is provided, the directions will be rendered in textual form in the panel specified.
if a callback is provided on the call to getDirections, then the google.maps.DirectionsResults object will be passed to the callback
The special location name __MYLOCATION__ can be used when the sensor option has been enabled to indicate the users current location.

The Test6 sample page illustrates the use of the directions functionality.

usage:

var points = [ '__MYLOCATION__', 'home' ];
$('#map').cggm2('getDirections',points[,callback]);

panToMarker:

This method will scroll the map to the specified off screen marker. The zoom level will not be adjusted. You can see an example of the usage of this method in the Test3 example.

usage:

$('#map').cggm2('panToMarker','test');

showInfoWindow:

This method will scroll the map to the specified marker (by name) and will display the infowindow for that marker. This method will only work if the marker specified exists, and there is a description or bubbletext for the marker.

usage:

$('#map').cggm2('showInfoWindow','test');

refresh:

This method forces a resize event on the map element, and forces the zoom to be adjusted to fit all of the markers. (similar to zoom_encompass) however it does not enable zoom_encompass automatically. This method can be used to force the map to re-draw.

usage:

$('#map').cggm2('refresh');

removeAllKmlLayers

todo

addKmlLayer

todo

addIcon

todo

Options:

center:

type: position

default: n/a

description: Optionally, specify the default center of the map on initial display. This option may be overridden by the sensor_center option (if sensor is enabled, and information is available).

example:

var opts = {
    center: [ '51.1234', '-110.1234' ],
    zoom:  8
};

default_icon:

type: string

default: The first icon in the icons list

description: The default icon to use for markers where an icon is not explicitly specified. The icon name must match one of the items specified in the icons array.

directions:

type: boolean

default: true

description: Indicates whether or not direction functionality is enabled.

directions_draw:

type: boolean

default: true

description: Indicates whether directions should be drawn on the map.

directions_panel:

type: string or node

default: none

description: Refers to the jquery selector or the node of a <div> that will be used to render the textual form of the directions (if any).

example:

var opts = {
    directions: 1,
    directions_panel: '#directions',
    directions_draw: 1,
    zoom:  8
};

directions_units:

type: string

default: metric

options: metric | imperial

description: Used when displaying or calculating directions this determines the units used for calculations.

icons:

type: array of icon objects

default: n/a

description: This option is used to define the icons that will be used to display markers on the map. If no icons are defined, google will use a standard icon for all markers.

idle_cb:

type: function

function arguments: The callback method accepts an instance of the cggm2 plugin as its only argument.

default: none

description: This callback is used to add functionality for when the map is idle (no user interaction). It can be used to add additional dynamic functionality to the map.

example:

var opts = {
  init_cb: function(cggm2) {
    // an example to hide a busy icon when the map is done doing its thing
    $('#loading').hide();
  }
};

infowindow:

type: boolean

default: true

description: Toggles infowindow functionality for the entire map. Note, individual markers still need a description or bubbletext defined.

infowindow_boxClass:

type: string

default: 'infoBox'

description: The CSS class name to use for the infowindow

infowindow_trigger:

type: string

default: 'click'

options: 'click' | 'mouseover'

description: Determine the event (click or mouseover) that will trigger the display of the infowindow

infowindow_cb:

type: function

function arguments: none

default: n/a

description: A callback function to handle the display of the infowindow

infowindow_content_cb:

type: function

function arguments: cggm2 object reference, marker object reference

default: n/a

description: A callback used to retrieve contents for populating the infowindow

kml:

type: array of kml objects

default: n/a

description: An array of objects representing the KML layers that should initially be displayed.

example:

var opts = {
     kml: [
        { 
            name: 'layer1',
            href: 'http://www.website.com/assets/layer1.kml'
        },
        {
            name: 'layer2',
            href: 'http://www.website.com/assets/layer2.kml'
        },
    ]
};

markers:

type: array of MarkerOption objects

default: n/a

description: An array of objects representing markers that should initially be displayed

example:

var opts = {
    markers: [
    {
      name: 'marker_1',
      title: 'Title or tooltip for marker 1',
      description: 'Extended information for marker 1',
      icon: 'home',
      position: [ '-45.1234', '51.1234' ]
    },
    {
      name: 'marker_2',
      title: 'Title or tooltip for marker 2',
      description: 'Extended information for marker 2',
      icon: 'home',
      position: [ '-51.1234', '45.1234' ]
    }
  ]
}

marker_click_cb:

todo

marker_mouseover_cb

todo

marker_mouseout_cb

todo

mylocationstr:

type: string

default: 'My Location'

description: This option controls the title used for the sensor_marker (if enabled).

nav_control s:

type: boolean

default: true

description: This flag controls wether navigation (panning) controls are displayed on the resulting map.

scale_controls:

type: boolean

default: true

description: This flag controls the display of scale controls

sensor:

type: boolean

default: true

description: This flag indicates whether or not the map will attempt to determine the user's location using embedded GPS or other mechanisms

note: This enables the collection of geolocation data by the browser (each customer may approve, or deny the reading of geolocation data by the browser).

sensor_center:

type: boolean

default: false

description: This flag is dependent upon the sensor flag above. If both are enabled, and the customer allows the browser to collect geolocation data then the map will be initially centered at the users location.

sensor_marker:

type: boolean

default: false

description: This flag is dependent on the sensor flag above. If both are enabled, then a marker will be placed at the users current location.

sensor_icon:

type: string

default: n/a

description: This option is dependent upon the sensor flag, and the sensor_marker flags above. This option specifies the name of the icon to use for the sensor marker. The icon name must be one of the icons specified with the icons parameter.

sv_controls:

type: boolean

default: true

description: This flag toggles the display of streetview controls on the map.

tooltip:

type: boolean

default: true

description: This flag toggles the use of the tooltip plugin, as opposed to standard HTML titles for markers. If this flag is enabled, and a marker has a title, then the tooltip plugin will be used for displaying the marker title.

tooltip_Class:

type: string

default: 'tooltip'

description: This option is dependent upon the tooltip flag above. If the tooltip flag is enabled then this option specifies the CSS class name of the element that will contain the tooltip.

type:

type: string

default: 'hybrid'

options: map | satellite | terrain | hybrid

description: This option defines the initial type of map that is displayed.

type_controls:

type: boolean

default: true

description: This flag defines wether controls to allow changing the map type will be displayed.

type_control_option:

type: string

default: 'default'

options: default | dropdown | small | horizontal_bar

description: This option is dependent upon the type_controls flag above. It defines the style of controls that will be displayed to allow the user to change the map type.

zoom:

type: integer

default: undefined

options: 1 to 17

description: This option defines the initial zoom level of the map. The greater the number the higher the zoom level. This option may be overriden by the zoom_encompass option below.

zoomControl:

type: boolean

default: true

description: This flag determines whether controls for zooming in and out will be visible on the map.

zoomControlOptions:

type: string

default: 'default'

options: default | large | small

description: This option defines the type of zoom controls that will be displayed on the map. This option is dependent upon the zoomControl option above.

zoom_encompass:

type: bool

default: false

description: If this option is enabled, then the original zoom of the map will be adjusted to fit all of the known markers. Similarly, if markers are dynamically added, the zoom will be adjusted so that all markers fit inside the map. Zoom is not adjusted upon removal of markers.

Events

The MarkerOptions Object:

The Icon Object:

The KML Object:

The Near Future

In the near future I will be extending the functionality and behavior of the icon and kml related methods and options. This may result in some backward compatibility issues.

Additionally, I intend to add on to the category functionality to allow dynamically displaying markers by categories, etc.

Examples:

Test1 Illustrates basic map creation. view the page source for more information.
Test2 Illustrates creating a map with multiple markers, tooltips, and custom marker icons.
Test3 Illustrates dynamically adding and removing markers, panning, and getting and setting options.
Test4 Illustrates creating markers statically (from hidden input elements).
Test5 is a demo of using the geolcation (sensor) services.
Test6 is a demo of using the directions functionality.

Credits:

I would like at this time to give much thanks to the jquery, and jquery-ui development team without which making this plugin would have been much more difficult (I just love jquery, it makes working in javascript almost pleasant).

Secondly, the google guys for providing a very extensive, free, and very powerful maps API.

Thirdly to the person who created the tooltip class to addon to the google maps api (author unknown, but here is a reference: http://medelbou.wordpress.com/2012/02/03/creating-a-tooltip-for-google-maps-javascript-api-v3/)

And last, but not least to the author(s) of the infobox library for google maps. (reference: http://google-maps-utility-library-v3.googlecode.com/svn/trunk/infobox/docs/reference.html).

cggm2 Plugin Reference

Table Of Contents

Features:

Dependencies:

Usage:

Calling plugin methods:

Retrieving plugin options:

Changing plugin options:

Adding Static Markers:

Methods:

directions_panel:

Examples:

Credits: